'\" t
.TH cm2_prarchive 1 "26 September 2006" "Code Manager II"

.SH NAME
cm2 project archive \- Archive a copy of an existing project

.SH SYNOPSIS
cm2 project archive  [\fB--project\fP \fIP\fP] [\fB--verbose\fP] [\fB--force\fP]
             [\fB--leave\fP \fIfile\fP] 

.SH DESCRIPTION
The \fIcm2 project archive(1)\fP utility allows a specified project to be archived as
a single file. This will archive just the underlying repository, not the working 
directories. However that provides enough to completely re-creat the working directories
if no files are currently checked out.

The file generated is written by \fIgtar(1)\fP and \fIgzip(1)\fP to generate a 
compressed archive.

By default this tool is used once development of a particular project is to be
moth-balled - the default arguments will remove the repository and generate 
an archive with the name of:

.TS
l.
project-YYYYMMDDHHMMSS.tgz
.TE

In the above name the 'YYYY', 'MM', 'DD', 'hh', 'mm', and 'ss' refer to the 
year, month, day-of-month, hour, minute and second of the time that the
archive was created.

Please note that the working directories that contain the source code control
are not affected by running this command - though of course the CM2 commands 
will no longer work since no meta-information for the directory will be found.

.SH ARGUMENTS
.TP 8
.B --verbose
Show more information regarding the archival process. This flag is 
recommended since the operation can take quite some time for large
projects. It also indicates the name of the archvie if one was not
specified via the \fI--keep\fP argument.
.TP
.B --force
By default the operation will fail if any files in the working 
directories are currently checked out. This is because checked out files
indicate that changes may be occuring still, or changes have occured but#
are not yet recorded in the code control repository.

In this instance using the \fI--force\fP option should be used with care -
it is likely that some information will be lost!
.TP
.B --project
Specifies the project to perform the archival action on. If this is
not specified it defaults to the project for which the current
working directory is part of.
.TP
.B --keep
Rather than perform a complete project archive instead just generate
a named archive. The name must be specified - including any extension
you wish the file to have.

The key difference here is that a copy of the code control repository
is created - the repository is left in place for further development.

This flag is particularly useful for backing up projects which are
still being worked on.

.SH EXIT CODES
The \fIcm2 project archive(1)\fP follows UNIX standard practise:

.TP 4
.B 0
The operation completed successfully - the archival [or copy] of the
project worked as expected.
.TP
.B >0
An error has occured - the reason for the error will be indicated
on the Standard Error channel.

.SH AUTHOR
The \fBCode Manager II\fP tool set was written by Simon Edwards, Proprius Consulting Ltd, (\fBwww.proprius.co.uk\fP).

.SH SEE ALSO
.BR cm2_cmpreleases(1),
.BR cm2_listreleases(1),
.BR cm2_tagrelease(1),
.BR cm2_tagremove(1)

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP.

